///////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2009 Summit Contributors.  
// See: http://code.google.com/p/tyemill/wiki/SummitContributors
//
// The name and logo of Summit are trademarks of TYEMILL, LLC - All Rights 
// Reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a 
// copy of this software and associated documentation files (the "Software"), 
// to deal in the Software without restriction, including without 
// limitation the rights to use, copy, modify, merge, publish, distribute, 
// sublicense, and/or sell copies of the Software, and to permit persons to 
// whom the Software is furnished to do so, subject to the following 
// conditions:
//
// The above copyright notice and this permission notice shall be included 
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
// DEALINGS IN THE SOFTWARE.
///////////////////////////////////////////////////////////////////////////////

package summit.basecamp.helpers
{
import summit.basecamp.constants.BasecampOperation;
import summit.basecamp.constants.BasecampResource;
import summit.net.BasecampRequest;
import flash.net.URLRequestMethod;

/**
 * Helpers for Basecamp time-entry operations.
 */
public class TimeEntryHelper
{
	/** @private constants **/
	private static const TYPE:String = BasecampResource.TIMEENTRY;
	private static const PATH_HELPER:String = "/time_entries/";
	
	/** @private **/
	public function TimeEntryHelper()
	{
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for creating a time-entry.
	 * 
	 * <p>Typically, the XML provided is based on the template returned from
	 * a call to <code>prepare</code>.
	 * 
	 * <p><code>project-id</code>, which represents the project that is 
	 * associated with time-entry, is required. <code>person-id</code> and 
	 * <code>date</code> are also required.
	 * 
	 * <p>In order for a time-entry to be created for a todo-item, the content 
	 * must contain a reference to an existing todo-item with the 
	 * <code>todo-item-id</code>. If a <code>todo-item-id</code> is not
	 * included, the entry is associated with a project referenced in the
	 * <code>project-id</code> element of the content.</p> 
	 * 
	 * @param XML Represents the time-entry to be created.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function create(content:XML):BasecampRequest
	{
		var data:String;
		
		SharedOperations.nullEmptyAssert(content.child("person-id")[0], 
			"TimeEntry requires a valid person-id", true);
			
		SharedOperations.nullEmptyAssert(content.child("date")[0], 
			"TimeEntry requires a valid date", true);
		
		
		if(content.hasOwnProperty("todo-item-id") && 
		content["todo-item-id"] != "")
		{
			// POST /todo_items/#{todo_item_id}/time_entries.xml
			// Returns HTTP status code 201 (Created) on success
			data = content.child("todo-item-id")[0];
			data = "/todo_items/" + data;
		}
		else
		{
			// it's empty - we don't need it - Basecamp can bounce the request
			// if it's present but not used.
			if(true == content.hasOwnProperty("todo-item-id"))
			{
				delete content.child("todo-item-id")[0];
			}
			
			// POST /projects/#{project_id}/time_entries.xml
			// Returns HTTP status code 201 (Created) on success
			data = content.child("project-id")[0];
			
			SharedOperations.nullEmptyAssert(data, 
			"content did not contain a valid project-id", true);
			
			data = "/projects/" + data;
		}
		
		return new BasecampRequest(data + "/time_entries.xml",
		URLRequestMethod.POST, TYPE, BasecampOperation.CREATE, content);  
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for deleting a time-entry.
	 * 
	 * @param id The id of the time-entry to be deleted.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */ 
	public static function destroy(id:String):BasecampRequest
	{
		// DELETE /time_entries/#{id}.xml
		// Returns HTTP status code 200 on success
		return SharedOperations.destroy(id, PATH_HELPER, TYPE); 
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for getting an existing 
	 * time-entry from the store.
	 * 
	 * <p>The XML returned is pre-filled with the existing values of
	 * the identified time-entry, and is ready to be resubmitted via the 
	 * <code>update</code> function.</p>
	 * 
	 * @param id The id of the time-entry to be retrieved.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */ 
	public static function edit(id:String):BasecampRequest
	{
		return SharedOperations.edit(id, PATH_HELPER, TYPE);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for reading a list of 
	 * time-entries.
	 * 
	 * <p>If a <code> projectId </code> is provided, the list is populated 
	 * with entries associated with the project given. If a 
	 * <code>todoItemId</code> is provided, the entries associated with items 
	 * are listed instead.</p>
	 * 
	 * <p>For lists of entries associated with projects, the first 50
	 * are returned in descending order by date. </p>
	 * 
	 * <p>For lists of entries associated with todo-items, all entries are
	 * returned in descending order by date.</p>
	 * 
	 * @param project_or_todoItem_id The id of a project or a todo-item.
	 * @param isTodoItemId <code>false</code> by default, <code>true</code>
	 * if the id passed is for a todo-item, and <code>false</code> if the id 
	 * passed is for a project id. 
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function list(project_or_todoItem_id:String, 
	isTodoItemId:Boolean = false):BasecampRequest
	{
		SharedOperations.nullEmptyAssert(project_or_todoItem_id,
		"project_or_todoItem_id"); 
		
		var path:String;
		// GET /todo_items/#{todo_item_id}/time_entries.xml
		// GET /projects/#{project_id}/time_entries.xml
		if(!isTodoItemId) path = "/projects/";
		else path = "/todo_items/";
		
		return new BasecampRequest(
		path + project_or_todoItem_id + "/time_entries.xml",
		URLRequestMethod.GET, TYPE, BasecampOperation.LIST); 
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for retrieving a template for a 
	 * new time-entry.
	 * 
	 * <p>The template retrieved is used with <code>create</code> to 
	 * submit a new time-entry.</p>
	 * 
	 * @param projectId The id of the project that is to be associated with 
	 * the time-entry when submitted via a call to <code>create</code>.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function prepare(projectId:String):BasecampRequest
	{
		SharedOperations.nullEmptyAssert(projectId, "projectId");
		
		return SharedOperations.prepare("/projects/" + projectId + 
			"/time_entries/new.xml", "project-id", projectId, 
			TYPE);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for reading a single time-entry.
	 * 
	 * @param id The id of the time-entry to be read.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function read(id:String):BasecampRequest
	{
		return SharedOperations.read(id, PATH_HELPER, TYPE);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for getting a report of 
	 * entries that match a given criteria.
	 * 
	 * <p>This action accepts the following query parameters: 
	 * “from”, “to”, “subject_id”, “todo_item_id”, “filter_project_id”, 
	 * and “filter_company_id”.</p>
	 * 
	 * <p>Both “from” and “to” should be dates in “YYYYMMDD” format, 
	 * and can be used to restrict the result to a particular date 
	 * range. (No more than 6 months’ worth of entries may be 
	 * returned in a single query, though).</p>
	 * 
	 * <p>The “subject_id” parameter lets you constrain the result 
	 * to a single person’s time entries. “todo_item_id” restricts 
	 * the result to only those entries relating to the given todo item. 
	 * “filter_project_id” restricts the entries to those for the given 
	 * project, and “filter_company_id” restricts the entries to those 
	 * for the given company.</p>
	 * 
	 * @param query The query string to be added to the report request. The 
	 * string should include the '?' with the arguments.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function report(query:String = ""):BasecampRequest
	{
		// GET /time_entries/report.xml -- see query parameters
		return new BasecampRequest("/time_entries/report.xml" + query,
		URLRequestMethod.GET, TYPE, BasecampOperation.REPORT);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for updating an existing 
	 * time-entry.
	 * 
	 * <p><code>content</code> submitted to <code>update</code> is typically
	 * retrieved from <code>edit</code>.</p>
	 * 
	 * @param content The updated XML content of an existing time-entry.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>. 
	 */ 
	public static function update(content:XML):BasecampRequest
	{
		// PUT /time_entries/#{id}.xml
		return SharedOperations.update(content, PATH_HELPER, TYPE);
	}
	
	
}
}
//////////////////////////////////////////////////////// gmarius@tyemill.com //